---
title: Zoom Plugin
description: Add zooming capabilities like zoom in, zoom out, fit-to-page, and marquee (area) zoom to your Vue PDF viewer.
searchable: true
---

import { Callout } from '@/components/callout'

# Zoom Plugin

The Zoom Plugin provides a comprehensive set of tools for controlling the magnification of PDF documents. It supports standard zoom-in/out, preset zoom levels (like fit-to-page and fit-to-width), and an interactive marquee zoom (also known as area zoom).

## Installation

This plugin is available as a separate package. You'll also need the `interaction-manager` plugin if you plan to use the marquee zoom feature.

```sh npm2yarn
npm install @embedpdf/plugin-zoom @embedpdf/plugin-interaction-manager
````

## Registration

Import `ZoomPluginPackage` and, if needed, `InteractionManagerPluginPackage`. Add them to the `plugins` array passed to the `<EmbedPDF>` component. You can configure the default zoom behavior upon registration.

```typescript {4-6, 22-25}
import { createPluginRegistration } from '@embedpdf/core'
// ... other imports
import {
  ZoomPluginPackage,
  ZoomMode,
} from '@embedpdf/plugin-zoom/vue'
import { InteractionManagerPluginPackage } from '@embedpdf/plugin-interaction-manager/vue'

const plugins = [
  // ... other essential plugins like Loader, Viewport, etc.
  createPluginRegistration(LoaderPluginPackage, {
    /* ... */
  }),
  createPluginRegistration(ViewportPluginPackage),
  createPluginRegistration(ScrollPluginPackage),
  createPluginRegistration(RenderPluginPackage),

  // Register the interaction manager (required for marquee zoom)
  createPluginRegistration(InteractionManagerPluginPackage),

  // Register and configure the zoom plugin
  createPluginRegistration(ZoomPluginPackage, {
    // Set the initial zoom level when a document loads
    defaultZoomLevel: ZoomMode.FitPage,
  }),
]
```

## Usage

The plugin exposes the `useZoom` composable to connect your UI components to its logic and state, and the `<MarqueeZoom />` component for area selection.

### Building a Zoom Toolbar

The `useZoom` composable is the primary way to interact with the plugin. It returns the current reactive zoom `state` and a `provides` object with methods to change the zoom.

```vue
<script setup lang="ts">
import { useZoom } from '@embedpdf/plugin-zoom/vue';

const { provides: zoom, state } = useZoom();
</script>

<template>
  <div v-if="zoom" class="toolbar">
    <span>{{ Math.round(state.currentZoomLevel * 100) }}%</span>

    <button @click="zoom.zoomOut()">-</button>
    <button @click="zoom.zoomIn()">+</button>
    <button @click="() => zoom.requestZoom(1.0)">Reset</button>

    <button @click="zoom.toggleMarqueeZoom()">Area Zoom</button>
  </div>
</template>
```

### Adding Marquee (Area) Zoom

To enable marquee zoom, place the `<MarqueeZoom />` component inside the default slot of your `<Scroller />`. This component will automatically render the selection rectangle when the marquee mode is active. It must be a child of `<PagePointerProvider>`.

```vue {2, 7}
<script setup lang="ts">
import { PagePointerProvider } from '@embedpdf/plugin-interaction-manager/vue';
import { MarqueeZoom } from '@embedpdf/plugin-zoom/vue';
</script>
<template>
  <Scroller>
    <template #default="{ page }">
      <PagePointerProvider v-bind="page">
        <RenderLayer :page-index="page.pageIndex" />
        <TilingLayer :page-index="page.pageIndex" :scale="page.scale" />
        <MarqueeZoom :page-index="page.pageIndex" :scale="page.scale" />
      </PagePointerProvider>
    </template>
  </Scroller>
</template>
```

## Live Example

This example combines the toolbar and the marquee zoom component into a complete viewer. Try clicking the area zoom button (the icon with the magnifying glass and crosshairs) and dragging a rectangle over the document.

import { ZoomExample } from '../code-examples/zoom-example';

<ZoomExample />

## API Reference

### Configuration (`ZoomPluginConfig`)

| Option | Type | Description |
| :--- | :--- | :--- |
| **`defaultZoomLevel`** | `ZoomMode \| number` | The initial zoom level. Can be a numeric scale factor (e.g., `1.5` for 150%) or a `ZoomMode` enum. <br />**Default**: `ZoomMode.Automatic` |
| **`minZoom`** | `number` | The minimum allowed numeric zoom level. <br />**Default**: `0.2` |
| **`maxZoom`** | `number` | The maximum allowed numeric zoom level. <br />**Default**: `60` |
| **`presets`** | `ZoomPreset[]` | An array of objects `{ name: string, value: ZoomMode \| number }` to define options for a zoom dropdown menu. |

### Composable: `useZoom()`

This composable connects your component to the zoom plugin's state and functions.

#### Returns

| Property | Type | Description |
| :--- | :--- | :--- |
| **`state`** | `Ref<ZoomState>` | A ref object containing the current zoom state. |
| **`provides`** | `Ref<ZoomCapability \| null>` | A ref object with methods to control zooming, or `null` if the plugin is not ready. |

#### `ZoomState` Properties

| Property | Type | Description |
| :--- | :--- | :--- |
| **`currentZoomLevel`** | `number` | The actual, calculated zoom factor applied to the document. |
| **`zoomLevel`** | `ZoomMode \| number` | The last *requested* zoom level, which might be a mode like `'fit-page'`. |

#### `ZoomCapability` Methods

| Method | Description |
| :--- | :--- |
| **`zoomIn()`** | Zooms in by one step. |
| **`zoomOut()`** | Zooms out by one step. |
| **`requestZoom(level)`** | Sets the zoom to a specific level (e.g., `1.0` or `ZoomMode.FitWidth`). |
| **`toggleMarqueeZoom()`** | Enables or disables the area zoom mode. |
| **`getPresets()`** | Returns the array of presets from the configuration. |

### Component: `<MarqueeZoom />`

Renders the visual rectangle when a user is selecting an area to zoom into.

#### Props

| Prop | Type | Description |
| :--- | :--- | :--- |
| **`pageIndex`** | `number` | (Required) The index of the page this component is rendered on. |
| **`scale`** | `number` | (Required) The current scale of the page. |
| **`class`** | `string` | (Optional) An optional CSS class for custom styling of the marquee rectangle. |
| **`stroke`** | `string` | (Optional) The color of the rectangle's border. |
| **`fill`** | `string` | (Optional) The background color of the rectangle. |